/*
 * Copyright 2014 JootMir Project
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 * 
 * Support: http://www.jootmir.org
 */
package org.jootmir.client.core.util;

import java.io.Serializable;
import java.util.ArrayList;

/**
 * 数据包
 * 
 * @author ShawRyan
 */
public interface Bundle {
	/**
	 * 从数据包中获取一个布尔值
	 * 
	 * @param key
	 * 		键
	 * @return 若存在该键值，返回储存于当前数据包中的布尔值；若不存在改键值，返回{@code false}
	 */
	boolean getBooleanExtra(String key);
	/**
	 * 从数据包中获取一个布尔值
	 * 
	 * @param key
	 * 		键
	 * @param defVal
	 * 		当不存在给定键值时返回的默认值
	 * @return
	 * 		弱存在该键值，返回储存于当前数据包中的布尔值；若不存在改键值，返回{@code defVal}
	 */
	boolean getBooleanExtra(String key, boolean defVal);
	/**
	 * 使用特定键将一个布尔值存入数据包
	 * 
	 * @param key
	 * 		要使用的键
	 * @param val
	 * 		要存入的数据
	 */
	void putBooleanExtra(String key, boolean val);
	
	/**
	 * 从数据包中获取一组布尔值
	 * 
	 * @param key
	 * 		键
	 * @return
	 * 		键对应数据
	 */
	boolean[] getBooleanArrayExtra(String key);
	/**
	 * 将一组布尔值存入数据包
	 * 
	 * @param key
	 * 		要使用的键
	 * @param val
	 * 		要存入的数据
	 */
	void putBooleanArrayExtra(String key, boolean[] val);
	
	/**
	 * 从数据包中获取单个字节数据
	 * 
	 * @param key
	 * 		键
	 * @return
	 * 		键值，若数据包中没有该键，则返回{@code 0}
	 */
	byte getByteExtra(String key);
	/**
	 * 从数据包中获取单个字节数据
	 * 
	 * @param key
	 * 		键
	 * @param defVal
	 * 		不存在该键值时返回的默认值
	 * @return
	 * 		数据包中的键值，若不存在该键值，则返回{@code defVal}
	 */
	Byte getByteExtra(String key, byte defVal);
	/**
	 * 使用特定键将一个字节数据存入数据包
	 * 
	 * @param key
	 * 		要使用的键
	 * @param val
	 * 		要存入的数据
	 */
	void putByteExtra(String key, byte val);
	
	/**
	 * 从数据包中获取一组字节数据
	 * 
	 * @param key
	 * 		键
	 * @return
	 * 		数据，不存在该键值时返回{@code null}
	 */
	byte[] getByteArrayExtra(String key);
	/**
	 * 使用特定键将一组字节数据存入数据包
	 * 
	 * @param key
	 * 		要使用的键
	 * @param val
	 * 		要存入的数据
	 */
	void putByteArrayExtra(String key, byte[] val);
	
	/**
	 * 从数据包中获取一个字符数据
	 * 
	 * @param key
	 * 		键
	 * @return
	 * 		返回特定键值；或{@code (char)0}，当不存在该键值时
	 */
	char getCharExtra(String key);
	/**
	 * 从数据包中获取一个字符数据
	 * 
	 * @param key
	 * 		键
	 * @param defVal
	 * 		默认值
	 * @return
	 * 		返回特定键值；或{@code defVal}，当不存在该键值时
	 */
	char getCharExtra(String key, char defVal);
	/**
	 * 将特定单个字符存入数据包
	 * 
	 * @param key
	 * 		要使用的键
	 * @param val
	 * 		要存入的数据
	 */
	void putCharExtra(String key, char val);
	
	/**
	 * 从数据包中获取一组字符数据
	 * 
	 * @param key
	 * 		键
	 * @return
	 * 		返回特定键值；或{@code null}，当不存在该键值时
	 */
	char[] getCharArrayExtra(String key);
	/**
	 * 将一组字符数据存入数据包
	 * 
	 * @param key
	 * 		要使用的键
	 * @param val
	 * 		要存入的数据
	 */
	void putCharArrayExtra(String key, char[] val);

	/**
	 * 从数据包中获取一组字符数据
	 * 
	 * @param key
	 * 		键
	 * @return
	 * 		返回特定键值；或{@code null}，当不存在该键值时
	 */
	CharSequence getCharSequenceExtra(String key);
	/**
	 * 从数据包中获取一组字符数据
	 * 
	 * @param key
	 * 		键
	 * @param defVal
	 * 		默认值
	 * @return
	 * 		返回特定键值；或{@code defVal}，当不存在该键值时
	 */
	CharSequence getCharSequenceExtra(String key, CharSequence defVal);
	/**
	 * 将一组字符数据存入数据包
	 * 
	 * @param key
	 * 		要使用的键
	 * @param val
	 * 		要存入的数据
	 */
	void putCharSequenceExtra(String key, CharSequence val);

	/**
	 * 从数据包中获取多组字符数据
	 * 
	 * @param key
	 * 		键
	 * @return
	 * 		返回特定键值；或{@code null}，当不存在该键值时
	 */
	CharSequence[] getCharSequenceArrayExtra(String key);
	/**
	 * 将多组字符数据存入数据包
	 * 
	 * @param key
	 * 		要使用的键
	 * @param val
	 * 		要存入的数据
	 */
	void CharSequenceArrayExtra(String key, CharSequence[] val);

	/**
	 * 从数据包中获取多组字符数据
	 * 
	 * @param key
	 * 		键
	 * @return
	 * 		返回特定键值；或{@code null}，当不存在该键值时
	 */
	ArrayList<CharSequence> getCharSequenceArrayListExtra(String key);
	/**
	 * 将多组字符数据存入数据包
	 * 
	 * @param key
	 * 		要使用的键
	 * @param val
	 * 		要存入的数据
	 */
	void putCharSequenceArrayListExtra(String key, ArrayList<CharSequence> val);

	/**
	 * 从数据包中获取一个双精度浮点数据
	 * 
	 * @param key
	 * 		键
	 * @return
	 * 		返回特定键值；或{@code 0}，当不存在该键值时
	 */
	double getDoubleExtra(String key);
	/**
	 * 从数据包中获取一个双精度浮点数据
	 * 
	 * @param key
	 * 		键
	 * @param defVal
	 * 		默认值
	 * @return
	 * 		返回特定键值；或{@code defVal}，当不存在该键值时
	 */
	double getDoubleExtra(String key, double defVal);
	/**
	 * 将一个双精度浮点数据存入数据包
	 * 
	 * @param key
	 * 		要使用的键
	 * @param val
	 * 		要存入的数据
	 */
	void putDoubleExtra(String key, double val);

	/**
	 * 从数据包中获取一组双精度浮点数据
	 * 
	 * @param key
	 * 		键
	 * @return
	 * 		返回特定键值；或{@code null}，当不存在该键值时
	 */
	double[] getDoubleArray(String key);
	/**
	 * 将一组双精度浮点数存入数据包
	 * 
	 * @param key
	 * 		要使用的键
	 * @param val
	 * 		要存入的数据
	 */
	void putDoubleArray(String key, double[] val);

	/**
	 * 从数据包中获取一个单精度浮点数据
	 * 
	 * @param key
	 * 		键
	 * @return
	 * 		返回特定键值；或{@code 0}，当不存在该键值时
	 */
	float getFloatExtra(String key);
	/**
	 * 从数据包中获取一个单精度浮点数据
	 * 
	 * @param key
	 * 		键
	 * @param defVal
	 * 		默认值
	 * @return
	 * 		返回特定键值；或{@code defVal}，当不存在该键值时
	 */
	float getFloatExtra(String key, float defVal);
	/**
	 * 将一个单精度浮点数存入数据包
	 * 
	 * @param key
	 * 		要使用的键
	 * @param val
	 * 		要存入的数据
	 */
	void putFloatExtra(String key, float val);

	/**
	 * 从数据包中获取一组单精度浮点数据
	 * 
	 * @param key
	 * 		键
	 * @return
	 * 		返回特定键值；或{@code null}，当不存在该键值时
	 */
	float[] getFloatArrayExtra(String key);
	/**
	 * 将一组单精度浮点数存入数据包
	 * 
	 * @param key
	 * 		要使用的键
	 * @param val
	 * 		要存入的数据
	 */
	void putFloatArrayExtra(String key, float[] val);

	/**
	 * 从数据包中获取一个整形数据
	 * 
	 * @param key
	 * 		键
	 * @return
	 * 		返回特定键值；或{@code 0}，当不存在该键值时
	 */
	int getIntExtra(String key);
	/**
	 * 从数据包中获取一个整形数据
	 * 
	 * @param key
	 * 		键
	 * @param defVal
	 * 		默认值
	 * @return
	 * 		返回特定键值；或{@code defVal}，当不存在该键值时
	 */
	int getIntExtra(String key, int defVal);
	/**
	 * 将一个整数存入数据包
	 * 
	 * @param key
	 * 		要使用的键
	 * @param val
	 * 		要存入的数据
	 */
	void putIntExtra(String key, int val);

	/**
	 * 从数据包中获取一组整形数据
	 * 
	 * @param key
	 * 		键
	 * @return
	 * 		返回特定键值；或{@code null}，当不存在该键值时
	 */
	int[] getIntArrayExtra(String key);
	/**
	 * 将一组整数存入数据包
	 * 
	 * @param key
	 * 		要使用的键
	 * @param val
	 * 		要存入的数据
	 */
	void putIntArrayExtra(String key, int[] val);

	/**
	 * 从数据包中获取一组整形数据
	 * 
	 * @param key
	 * 		键
	 * @return
	 * 		返回特定键值；或{@code null}，当不存在该键值时
	 */
	ArrayList<Integer> getIntegerArrayListExtra(String key);
	/**
	 * 将一组整数存入数据包
	 * 
	 * @param key
	 * 		要使用的键
	 * @param val
	 * 		要存入的数据
	 */
	void putIntegerArrayListExtra(String key, ArrayList<Integer> val);

	/**
	 * 从数据包中获取一个长整型数据
	 * 
	 * @param key
	 * 		键
	 * @return
	 * 		返回特定键值；或{@code 0}，当不存在该键值时
	 */
	long getLongExtra(String key);
	/**
	 * 从数据包中获取一个长整型数据
	 * 
	 * @param key
	 * 		键
	 * @param defVal
	 * 		默认值
	 * @return
	 * 		返回特定键值；或{@code defVal}，当不存在该键值时
	 */
	long getLongExtra(String key, long defVal);
	/**
	 * 将一个长整数存入数据包
	 * 
	 * @param key
	 * 		要使用的键
	 * @param val
	 * 		要存入的数据
	 */
	void putLongExtra(String key, long val);

	/**
	 * 从数据包中获取一组长整型数据
	 * 
	 * @param key
	 * 		键
	 * @return
	 * 		返回特定键值；或{@code null}，当不存在该键值时
	 */
	long[] getLongArrayExtra(String key);
	/**
	 * 将一组长整数存入数据包
	 * 
	 * @param key
	 * 		要使用的键
	 * @param val
	 * 		要存入的数据
	 */
	void putLongArrayExtra(String key, long[] val);

	/**
	 * 从数据包中获取一个可序列化数据
	 * 
	 * @param key
	 * 		键
	 * @return
	 * 		返回特定键值；或{@code null}，当不存在该键值时
	 */
	Serializable getSerializableExtra(String key);
	/**
	 * 将一个可序列化数据存入数据包
	 * 
	 * @param key
	 * 		要使用的键
	 * @param val
	 * 		要存入的数据
	 */
	void putSerializableExtra(String key, Serializable val);

	/**
	 * 从数据包中获取一个短整型数据
	 * 
	 * @param key
	 * 		键
	 * @return
	 * 		返回特定键值；或{@code 0}，当不存在该键值时
	 */
	short getShortExtra(String key);
	/**
	 * 从数据包中获取一个短整型数据
	 * 
	 * @param key
	 * 		键
	 * @param defVal
	 * 		默认值
	 * @return
	 * 		返回特定键值；或{@code defVal}，当不存在该键值时
	 */
	short getShortExtra(String key, short defVal);
	/**
	 * 将一个短整型存入数据包
	 * 
	 * @param key
	 * 		要使用的键
	 * @param val
	 * 		要存入的数据
	 */
	void putShortExtra(String key, short val);

	/**
	 * 从数据包中获取一组短整型数据
	 * 
	 * @param key
	 * 		键
	 * @return
	 * 		返回特定键值；或{@code null}，当不存在该键值时
	 */
	short[] getShortArrayExtra(String key);
	/**
	 * 将一组短整型存入数据包
	 * 
	 * @param key
	 * 		要使用的键
	 * @param val
	 * 		要存入的数据
	 */
	void putShortArrayExtra(String key, short[] val);

	/**
	 * 从数据包中获取一个字符串数据
	 * 
	 * @param key
	 * 		键
	 * @return
	 * 		返回特定键值；或{@code null}，当不存在该键值时
	 */
	String getStringExtra(String key);
	/**
	 * 从数据包中获取一个字符串数据
	 * 
	 * @param key
	 * 		键
	 * @param defVal
	 * 		默认值
	 * @return
	 * 		返回特定键值；或{@code defVal}，当不存在该键值时
	 */
	String getStringExtra(String key, String defVal);
	/**
	 * 将一个字符串存入数据包
	 * 
	 * @param key
	 * 		要使用的键
	 * @param val
	 * 		要存入的数据
	 */
	void putStringExtra(String key, String val);

	/**
	 * 从数据包中获取一组字符串数据
	 * 
	 * @param key
	 * 		键
	 * @return
	 * 		返回特定键值；或{@code null}，当不存在该键值时
	 */
	String[] getStringArrayExtra(String key);
	/**
	 * 将一组字符串存入数据包
	 * 
	 * @param key
	 * 		要使用的键
	 * @param val
	 * 		要存入的数据
	 */
	void putStringArrayExtra(String key, String[] val);

	/**
	 * 从数据包中获取一组字符串数据
	 * 
	 * @param key
	 * 		键
	 * @return
	 * 		返回特定键值；或{@code null}，当不存在该键值时
	 */
	ArrayList<String> getStringArrayListExtra(String key);
	/**
	 * 将一组字符串存入数据包
	 * 
	 * @param key
	 * 		要使用的键
	 * @param val
	 * 		要存入的数据
	 */
	void putStringArrayListExtra(String key, ArrayList<String> val);
}